Add Wayfinder and AI tools guidance by bdenham · Pull Request #953 · commerce-docs/microsite-commerce-storefront

bdenham · 2026-07-17T16:11:18Z

Purpose of this pull request

Restructures the AI docs section around a new Wayfinder page. Renames and rewrites existing AI pages into a clearer sidebar flow ("AI Integrations"), replaces "Build with AI" with a fallback-docs page, and updates redirects for the moved slugs.

Associated JIRA ticket

COMDOX-1745

Staging preview

https://commerce-docs.github.io/microsite-commerce-storefront/ai/

Affected pages

src/content/docs/ai/wayfinder.mdx — new
src/content/docs/ai/static-text-files.mdx — new, replaces ai/build-with-ai.mdx
src/content/docs/ai/boilerplate-skills.mdx — new, replaces ai/ai-agent-skills.mdx
src/content/docs/ai/index.mdx — rewritten as the combined installation walkthrough
src/content/docs/boilerplate/index.mdx — link update after the boilerplate-skills rename
astro.sidebar.mjs — AI section relabeled and reordered
astro.redirects.mjs — redirects added for the two renamed pages

Links to source code

N/A

Summary

Added the Wayfinder page, explaining what it is, when to use it, and how to add it to an AI coding agent; linked it from the rewritten AI overview.
Renamed/rewrote ai-agent-skills.mdx → boilerplate-skills.mdx and build-with-ai.mdx → static-text-files.mdx, updating the one inbound link on boilerplate/index.mdx.
Rewrote index.mdx as a single walkthrough covering all three integrations (boilerplate skills, Dropins MCP, Wayfinder).
Relabeled the sidebar section from "Build with AI" to "AI Integrations," reordered it, and added redirects for both renamed pages.

Testing

Ran a full local build (npm run build) to confirm starlight-links-validator passes with no broken links, and reviewed the updated content for clarity, structure, and internal links.

The self-reported "Debug mode" instruction depended on the agent noticing and recalling the integration order from memory, and couldn't verify anything for a response where no skill was invoked. Document a hook that observes actual tool calls instead, safe to leave in place permanently rather than removed after one-time verification.

…uracy Bring the AI integrations section (5 pages) from WIP to a reviewed state: fix structural gaps (missing Prerequisites, buried headings, no verification step), unify agent/editor terminology across pages, apply editorial guidelines (active voice, pronoun clarity, list punctuation), and verify factual claims — Node.js version requirements and Dropins MCP's B2B coverage — against source instead of assuming. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

A citation-only check turned out to be unreliable in live testing — an agent can answer confidently from training data and simply omit a citation, which looks identical to Wayfinder not firing at all. Add a direct follow-up question asking the agent whether it fetched external documentation or answered from its own knowledge; that self-report proved to be the more reliable signal when validated against a real project. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…mdx slug

…work)

…and a follow-up)

… checks branch content, not redirects)

OscarMerino · 2026-07-21T07:54:12Z

+
+Your agent retrieves this file at the start of a session and follows its routing rules for the duration of the conversation. There is no package to install and no configuration file to create.
+
+<Aside type="note">


This Aside has no title, which means a reader has to read the body to understand what it's about. A title like "Network permissions" would help.

OscarMerino · 2026-07-21T07:55:06Z

+   ```
+
+
+3. **Add Wayfinder.** Wayfinder routes questions about Commerce Admin, App Builder, or Document Authoring to the right documentation site. See [Wayfinder](/ai/wayfinder/) for details. Add this line to `AGENTS.md` or `CLAUDE.md` at your project root:


Step 1 runs aio commerce extensibility tools-setup, which creates AGENTS.md. But a user reading step 3 in isolation won't know to create the file first. One sentence would close the gap: "If AGENTS.md doesn't exist yet, create it at your project root."

There's also not a need to "add wayfinder" if you cloned the boilerplate. It is already included in the default AGENTS.md as of hlxsites/aem-boilerplate-commerce#1264.

OscarMerino · 2026-07-21T07:55:09Z

+
+   The last command prompts you to choose a starter kit, your coding agent, and, if needed, a package manager. See [Install the skills](/ai/boilerplate-skills/#install-the-skills) for details.
+
+2. **Add the Dropins MCP (Model Context Protocol) server.** Add the following to your editor's MCP config file — for Claude Code, that's `.mcp.json` at your project root. See [Dropins MCP](/ai/dropins-mcp/) for the exact file and format for other editors:


The JSON snippet here duplicates content from the dedicated Dropins MCP page, but only partially. It shows the Claude Code/VS Code Copilot format, which will silently break for Cursor users. The step then links to the full page anyway, so the snippet isn't saving anyone a click.

Consider dropping the snippet entirely and just sending readers to the dedicated page:

Add the Dropins MCP server to your editor. See Dropins MCP for the config snippet for your editor, then return here for step 3.

That keeps the walkthrough complete without duplicating content that already has a maintained home.

OscarMerino · 2026-07-21T07:55:13Z

+
+Before you install the integrations, make sure you have the following:
+
+- **Node.js 22 or later** — The highest requirement across all three integrations.


Node.js version conflict: the existing dropins-mcp.mdx (unchanged by this PR) says "Node.js 18 or later". A reader who follows the combined walkthrough in index.mdx and then reads the Dropins MCP page directly will see contradicting requirements.

OscarMerino · 2026-07-21T07:55:19Z

+<Aside type="note" title="Drop-in API accuracy">
+Four of these skills — researcher, drop-in developer, project manager, and tester — call Dropins MCP tools to verify slots, events, API functions, and configuration against your project's source, not published documentation. Without the [Dropins MCP server](/ai/dropins-mcp/) installed, most checks fall back to local TypeScript definitions. A few, such as generating slot boilerplate, have no fallback. For the underlying APIs, see the [Blocks reference](/boilerplate/blocks-reference/) and [Drop-in components](/dropins/all/introduction/).
+
+Adding the MCP (Model Context Protocol) server or [Wayfinder](/ai/wayfinder/) doesn't automatically integrate them with this workflow. See [Install the integrations](/ai/#installation-steps), step 4, for the precedence rule.


Numbered step references across pages are maintenance risks. If the step order in index.mdx ever changes, this reference silently breaks. Consider linking to a stable anchor (/ai/#coordination-instructions) or rephrasing without the step number.

sirugh · 2026-07-21T14:43:50Z

+import Aside from '@components/Aside.astro';
+import Link from '@components/Link.astro';
+
+<Link href="https://github.com/adobe-commerce/wayfinder" text="Wayfinder" /> is a free, open-source router for AI coding agents. Adobe Commerce documentation is spread across several separate sites, so an agent can easily search the wrong one or answer from outdated training data. Wayfinder reads your question, routes it to the right source, and tells your agent to fetch and cite that source before it answers.


Technical nit: Wayfinder is not a running application, it's just context/instructions for an agent.

bdenham and others added 9 commits July 17, 2026 11:05

wip wayfinder and ai topics

e69c7b0

shortened page with essentials only

8c47d5f

wip ai work

7bae3eb

creating ai integration docs

4057cc7

WIP on combining AI integrations

f56512b

Fix redirect target for /ai/build-with-ai to match static-text-files.…

cf85219

…mdx slug

bdenham mentioned this pull request Jul 21, 2026

Polish Dropins MCP docs #958

Merged

bdenham added 2 commits July 20, 2026 22:30

Restore common-events.mdx (accidental deletion, unrelated to AI docs …

e7a75ac

…work)

Peel dropins-mcp.mdx and boilerplate/index.mdx into separate PRs (#958 …

ccafcfa

…and a follow-up)

bdenham mentioned this pull request Jul 21, 2026

Update boilerplate skills link on boilerplate overview page #959

Closed

bdenham self-assigned this Jul 21, 2026

bdenham added feedback Update based on internal or external stakeholder feedback major-update Significant original updates to existing content new-topic A major update published as an entirely new document labels Jul 21, 2026

Remove .vscode/settings.json change from this PR

9573f08

bdenham requested review from OscarMerino, jcalcaben and sirugh July 21, 2026 03:48

Fold boilerplate/index.mdx link fix back into this PR (link validator…

6835cc4

… checks branch content, not redirects)

OscarMerino reviewed Jul 21, 2026

View reviewed changes

sirugh reviewed Jul 21, 2026

View reviewed changes

bdenham added 2 commits July 21, 2026 12:04

Merge branch 'release' into wayfinder-docs

4697836

Merge branch 'release' into wayfinder-docs

0910598

bdenham added 2 commits July 21, 2026 14:27

Review updates

185e5a6

refine writing

6f22381

bdenham requested review from OscarMerino and sirugh July 21, 2026 22:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add Wayfinder and AI tools guidance#953

Add Wayfinder and AI tools guidance#953
bdenham wants to merge 17 commits into
releasefrom
wayfinder-docs

bdenham commented Jul 17, 2026 •

edited

Loading

Uh oh!

OscarMerino Jul 21, 2026

Uh oh!

OscarMerino Jul 21, 2026

Uh oh!

sirugh Jul 21, 2026

Uh oh!

OscarMerino Jul 21, 2026 •

edited

Loading

Uh oh!

OscarMerino Jul 21, 2026

Uh oh!

OscarMerino Jul 21, 2026

Uh oh!

sirugh Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		Your agent retrieves this file at the start of a session and follows its routing rules for the duration of the conversation. There is no package to install and no configuration file to create.

		<Aside type="note">

		```


		3. Add Wayfinder. Wayfinder routes questions about Commerce Admin, App Builder, or Document Authoring to the right documentation site. See [Wayfinder](/ai/wayfinder/) for details. Add this line to `AGENTS.md` or `CLAUDE.md` at your project root:


		The last command prompts you to choose a starter kit, your coding agent, and, if needed, a package manager. See [Install the skills](/ai/boilerplate-skills/#install-the-skills) for details.

		2. Add the Dropins MCP (Model Context Protocol) server. Add the following to your editor's MCP config file — for Claude Code, that's `.mcp.json` at your project root. See [Dropins MCP](/ai/dropins-mcp/) for the exact file and format for other editors:


		Before you install the integrations, make sure you have the following:

		- Node.js 22 or later — The highest requirement across all three integrations.

Uh oh!

Conversation

bdenham commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose of this pull request

Associated JIRA ticket

Staging preview

Affected pages

Links to source code

Summary

Testing

Uh oh!

OscarMerino Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

OscarMerino Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

sirugh Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

OscarMerino Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

OscarMerino Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

OscarMerino Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

sirugh Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bdenham commented Jul 17, 2026 •

edited

Loading

OscarMerino Jul 21, 2026 •

edited

Loading